Release 10.1A: OpenEdge Development:
Debugging and Troubleshooting

Making the process ready for debugging

Before you can start the Debugger in attachable mode, you have to ready the process for debugging. The process can be any 4GL (GUI or character mode) client, WebSpeed agent, or AppServer process, but not a WebClient process. You can make the process ready for debugging by:

Using the Debugger window
Using the Ready Attachable Debugger (-debugReady) startup parameter
Using the proDebugConfig command

While the 4GL interpreter is debug-ready, it might run slower than normal. Therefore, you should turn on this capability only when you intend to use the Debugger in attachable mode.

Using the Debugger window

If you are running the Debugger on the same machine as the process to be debugged, you can make a process debug-ready through the Debugger window. In this case, the user interface mirrors what you do when you run the proDebugConfig command. You provide the same information and receive the same message feedback. For information, see the "Attach to Process dialog box" section.

Using the Ready Attachable Debugger (-debugReady) startup parameter

The Ready Attachable Debugger (-debugReady) startup parameter makes a process ready for debugging at startup. For example:

-debugReady port-number

port-number

A port number or zero (0). If you specify a known port number, the 4GL interpreter attempts to use that port to create a socket to await a connection from the Debugger. If the port is in use, the interpreter reports the error and continues to run, without making the process ready for debugging.

If you specify 0, the interpreter determines a usable port number and reports that number to you during startup processing, as follows:

For a GUI client, in an Alert box (even if running in batch mode).
For a WebSpeed agent, in the WebSpeed log file.
For an Appserver process, in the AppServer log file.
For a client process running on UNIX, in the shell window (even if running in batch mode).

If you attempt to ready debugging on startup and debugging is not enabled for the installation (see the "Enabling debugging" section), you receive a warning message, and then startup continues. If you specify -debugReady and -debug in the same startup parameter, the 4GL interpreter reports this as invalid and shuts down.

Note: All WebSpeed agents and AppServer processes started by the same broker use the same startup parameter. If you use such a broker configuration, do not specify a port number with the -debugReady startup parameter.

Using the proDebugConfig command

The proDebugConfig command gives you a way to instruct a running 4GL client, WebSpeed agent or single AppServer process to make itself ready for debugging. You must execute the command on the same machine as the process you are enabling. You can run the command from either a UNIX shell or a Windows Proenv shell (Programs OpenEdge Proenv from the Start menu). The command has the following syntax:

Syntax

proDebugConfig [process Id] [-ready {yes | no}] [-port port-number]

process Id

The ID of the process you want to enable for debugging. If you don’t specify an ID, the command searches the local machine and displays a list of running OpenEdge processes and prompts you to enter an ID shown in the list.

On UNIX the list might resemble the following:

mscat 16273 1 0 Jul 08 pts/37 0:03 /pro/dlc/bin/_progres -p /usr1/InvApp/main.p -T /tmp -h 10 mrdog 9295 26391 0 10:57:38 pts/40 0:01 /pro/dlc/bin/prowin32 -pf startup.pf

in Windows:

C:\pro\dlc\bin\_progres.exe 16273 C:\pro\dlc\bin\prowin32.exe 9295

Enter the process ID, for example, 9295, and press ENTER. Press CTRL+C to cancel the command.

-ready {yes | no}

Turns the debug-ready state on or off. If you specify yes, and the process is currently ready for debugging (either from a previous command execution or the -debugReady startup parameter), the command displays a message to that effect that includes the port number used for the connection. If you specify no, and the ready state was already turned off by a previous command execution, or was never ready to begin with, the command displays a message to that effect. The default is yes.

port-number

A port number or zero (0). If you specify a known port number, the 4GL interpreter attempts to use that port to create a socket to await a connection from the Debugger. If the port is in use, proDebugConfig reports the error and the 4GL interpreter continues to run, without making the process ready for debugging. If you do not specify the parameter or you specify 0, the interpreter determines a usable port number, which the command displays to you in the shell.

If the command succeeds in making the process debug-ready, it displays a message to that effect and terminates. If the command execution is unsuccessful, the command outputs a message to the shell, the contents of which might indicate one of the following:

You entered an incorrect process ID.
The process you are trying to ready for debugging might be from an earlier release or a non-OpenEdge process.
The 4GL interpreter is busy, perhaps performing an extremely slow query, waiting on a database lock or a response from an AppServer, and is thus unable to respond in a timely manner. The attempt, in this case, times out after 25 seconds.
The 4GL interpreter is unable to respond, pending completion of one of the following statements:
MESSAGE VIEW-AS ALERT BOX (GUI Windows).
READKEY (character mode Windows).
PAUSE (character mode Windows).

The command displays a message, instructing you to satisfy the condition and retry the operation.

You tried to change the debug-ready state of a process that is already in a debug session.

For a WebSpeed agent, when the command successfully alters the debug-ready state, it writes the status (on or off) to the WebSpeed log file.

For an AppServer process, when the command successfully alters the debug-ready state, it writes the status (on or off) to the server log file.

If the AppServer is currently waiting for a new request, the Debugger will get control on the next line of executable 4GL code.

For more information on starting the debugger in attachable mode, see the "Debugging in attachable mode" section.